fix(native-api): return the parser's reason for a rejected managed entry - #140

Problem

POST /api/v1/nodes with a link that honk cannot parse returned the generic 422 message "The main source cannot hold this node name and share link" (crates/honk-core/src/native_api/config/coordinator.rs:384-389, origin/feat/native-api 0e9f2a3): append_node_source collapsed every failure into the unit SourceEditError (crates/honk-config/src/parser/source_edit.rs:36-38, 400-445) and discarded the parser's diagnostic, so an XHTTP extra such as {"xPaddingBytes":"0-10"} gave no reason, although the contract asks for a sanitized reason in error.message. The three XHTTP range checks also shared one message, "XHTTP range exceeds supported bounds" (crates/honk-config/src/node/xhttp.rs:571-579). Separately, a client editing a node through a source write cannot tell a skipped entry from an accepted one: the node parser downgrades a link failure to a warning (crates/honk-config/src/parser/entries.rs:134-147), so the reload succeeds and the node disappears, and nothing stated which warnings an accepted link can produce.

How I fixed it

SourceEditError now carries an optional static reason, which managed_entry fills from the parse error, the last warning of a skipped entry, or full admission; node and provider creation return it as error.message and keep the generic message otherwise, with unchanged details and no submitted value. Each XHTTP range names its Xray key and bounds. Node::parse_share_link debug-asserts that a link's warnings use legacy-* codes, which both of today's emitters already do, and doc/*/reference/nodes.md states that rule so a client can validate one node {} declaration in syntax mode and treat any other warning as a dropped entry; doona's node dialog (Zakkaus/doona#542) relies on it. doc/*/reference/api.md and .agents/rules/configuration.md are updated.

Verified

cargo test -p honk-config: 565 passed, including managed_node_rejection_keeps_the_static_parser_reason, which fails with the xhttp.rs change reverted (left XHTTP range exceeds supported bounds). cargo test -p honk-core --features native-api --lib native_api::: 398 passed, including rejected_node_links_report_the_static_parser_reason, which fails with the coordinator.rs change reverted (left the generic message). cargo clippy --all --all-targets --features honk-core/native-ui -- -D warnings, cargo clippy --workspace --all-targets --no-default-features -- -D warnings and cargo fmt --all -- --check are clean, and each commit passes cargo check -p honk-config -p honk-core --features honk-core/native-api. Against a local honk-core with mock eBPF and doona served from dist/, POST /nodes with {"scMaxEachPostBytes":0,"headers":{"X-K":"private-value"}} returned 422 "XHTTP scMaxEachPostBytes must stay within 1-16777216" without the header value and wrote nothing, and syntax validation of that declaration returned the same message as an invalid-config-value warning. Not run: just test-ci, the full honk-core and workspace suites, just test-netns; honk-core test builds were OOM-killed at default parallelism here and ran with -j4 and debug info off. The provider-side reason has no test, because I found no input that passes the earlier URL and user-agent checks and still fails the parser.

Follow-up, not changed here: VMess JSON XHTTP still collapses every option failure into "unsupported or invalid VMess XHTTP option" (crates/honk-config/src/share_link/xhttp.rs:151, 168-171, which discard the mode-conflict and from_xray_extra messages), so a VMess link gets no field-level reason; this predates the branch. Issues are disabled on this repository, so it is recorded here.

AI disclosure: the code, tests, docs and this description were written by an LLM agent (omp, Claude), with separate adversarial and code-quality review passes whose findings are addressed here. A maintainer has not yet reviewed the result.

• just fmt, just lint and just test-ci pass.
• I updated doc/en/ and doc/zh/ if I changed documented behaviour.
• If I used AI: it followed CONTRIBUTING.md and AGENTS.md, and Verified shows what I ran, not guesses.